Voicebot Conversation

The icon for the Voicebot Conversation action.

Integrates a self-service virtual agent A software application that handles customer interactions in place of a live human agent. with voice scripts. Your virtual agent must support this action.

The Voicebot Conversation action is only for use with very simple bots or when you are using a SIP Protocol used for signaling and controlling multimedia communication sessions such as voice and video calls. backchannel connection. It does not allow the Studio script to customize or control the virtual agent's behavior from turn to turn. If you need to customize the virtual agent's behavior between turns in the conversation and if your virtual agent provider supports it, use the Voicebot Exchange action.

This action interacts directly with the virtual agent and passively monitors the conversation in real time. The virtual agent analyzes the conversation for intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish and context from a constant audio stream. It then returns appropriate responses to the contact. When the virtual agent indicates the conversation is over, the action continues the Studio script. The action passes along any relevant information for screen pops State that allows an agent to complete work requirements after finishing an interaction, agent routing, and so on.

This action is not recommended for use with Google Dialogflow ES. It's also not recommended for use with Google Dialogflow CX unless you're using a SIP backchannel connection.

Double-clicking this action opens the Virtual Agent Hub, where you can manage all of your virtual agents.

Supported Script Types

The icon for the Phone script type - an old-style phone handset with curved lines indicating sound coming out of it.

Phone

Comparison of Similar Actions

The following actions have similar functions, but with some key differences:

Textbot Conversation: This action is only suitable for very simple virtual agents. It doesn't allow for customization of the virtual agent's behavior from turn to turn. It's not currently supported in CXone.
Textbot Exchange: This action is used for complex virtual agent interactions. It allows you to include exchange parameters and to customize various aspects of the conversation between contact and virtual agent.
Voicebot Conversation: This action is only suitable for very simple virtual agents. It doesn't allow for customization of the virtual agent's behavior from turn to turn. If you want to use a SIP backchannel connection and your virtual agent supports it, you must use Voicebot Conversation.
Voicebot Exchange: This action is used for complex virtual agent interactions. It allows you to include exchange parameters and to customize various aspects of the conversation between contact and virtual agent.

Supported Virtual Agents

This action supports the following virtual agents:

CXone SmartAssist Powered by Amelia (not recommended)
Google Dialogflow CX (not recommended)
Google Dialogflow ES (not recommended)

Before you can assign a virtual agent to this action, you must add and configure an app for the virtual agent in Virtual Agent Hub. You only need one app for each virtual agent you use. You can assign the same app to multiple virtual agent actions in your scripts. Refer to the help page for the virtual agent provider you're using for configuration details.

Input Properties

These properties define data that the action uses when executing.

Property	Description
virtualAgentID	The name of the virtual agent selected in the Virtual Agent Hub. When you assign a virtual agent app to a Studio action in Virtual Agent Hub, it automatically populates this property. The name is the name used in the Virtual Agent (Bot) Name field in the Virtual Agent Hub app.
customPayload	Configure this property only if you need to pass custom payload data to the virtual agent. The custom payload object is populated from the Studio script. You can use it to pass information such as the contact's name from a CRM Third-party systems that manage such things as contacts, sales information, support details, and case histories. to be used in a Welcome message. Enter the name of the JSON object that passes data from the script to the virtual agent. You must define the custom payload object in a Snippet action. The object must be converted to JSON, either in the snippet or in the customPayload property. Requirements for specific virtual agent providers: Amazon Lex V1: This property is required even if you don't need to pass data to the virtual agent. Add a snippet with a placeholder value. Google Dialogflow ES: This property is used to pass the context for an intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. Review the best practices for custom payload with Google Dialogflow ES to ensure you handle it appropriately. Google Dialogflow CX: Review the best practices for custom payload with Google Dialogflow CX to ensure you handle it appropriately. Don't use this property if you need to process data that the virtual agent returns to the script. Instead, use the customPayloadVarName (out) variable.
maxTimeouts	Sets the number of no-utterance exchanges before routing to the error fallback branch.
maxNotUnderstood	Sets the number of failed intent recognition exchanges before routing to the error fallback branch.

Output Properties

These properties contain variables that hold data returned from executing the action. They're available for reference and use when the action completes.

Property	Description
customPayloadVarName (out)	Returns custom JSON data from the virtual agent to the script. Use this variable when you want the script to process data that the virtual agent provides. May contain fulfillment data. If you want to provide data to the virtual agent, use the customPayload property.
errorDetailsVarName (out)	Prompts the error intent sequence; can lead to a transfer to a live agent.
intentInfoVarName (out)	A variable that holds details from the virtual agent indicating current user intent.

Property

Description

customPayloadVarName (out)

Returns custom JSON data from the virtual agent to the script. Use this variable when you want the script to process data that the virtual agent provides. May contain fulfillment data.

If you want to provide data to the virtual agent, use the customPayload property.

errorDetailsVarName (out)

Prompts the error intent sequence; can lead to a transfer to a live agent.

intentInfoVarName (out)

A variable that holds details from the virtual agent indicating current user intent.

Result Branch Conditions

Result branch conditions allow you to create branches in your script to handle different outcomes when an action executes.

Condition	Description
OnBotSessionComplete	Path taken when the virtual agent indicates that the conversation has ended. If you're using a SIP backchannel connection and want the virtual agent to be able to pass the contact back to the script to talk to a live agent, you must include the Live Agent Handoff snippet in your script.
OnError	Path taken when there is an unexpected problem (for example, poor connectivity, syntax errors, and so forth). The _ERR variable should be populated with a condensed explanation of the problem.
OnDTMFBreakout	Path taken when a DTMF Signaling tones that are generated when a user presses or taps a key on their telephone keypad. rule in the script was met.
OnUserInputTimeout	Path taken when there is no response by the user in the time specified in the Prompt Behavior snippet (either the Default or the Next Prompt Behavior snippet). For Google Dialogflow, you can configure the event that you want to happen in the Virtual Agent Hub Dialogflow app. For Dialogflow ES, configure the Timeout Event field. For Dialogflow CX, configure the Timeout Event Handler. If no event is configured, the default is to use the default fallback intent as configured in the Dialogflow console. If you want, you can configure this branch to use different events at different points in your script.
OnUserInputNotUnderstood	Path taken when the virtual agent doesn't understand the contact's response or when the contact times out.

Snippet Action Code

One or more of this action's properties require a Snippet action with the following custom code:

Custom Payload.
Live Agent Handoff (only for SIP backchannel connections).

Best Practices for Custom Payload with Google Dialogflow CX

When using this action with Google Dialogflow CX. follow these best practices for integrating custom payloads:

Dialogflow CX doesn't use contexts to pass data to Dialogflow intents The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish like Dialogflow ES does.
You can pass custom data to Dialogflow CX using JSON key-value pairs. In a Snippet actionaction in your script, create a dynamic customPayload object and add the key-value pairs to it. For example:
```
DYNAMIC customPayload
customPayload.ani = ani
customPayload.contactID = contactId
customPayload.masterContactId = masterId
customPayloadJSON = "{customPayload.asJSON()}"	
```
In the Exchange or Conversation action in your script, configure the customPayload property with variable that has the asJSON() function in its value. You can find this variable in the customPayload object.
Pass the customPayload JSON to the virtual agent using the Payload property of QueryParameters. See Google documentation on QueryParameters for Google Dialogflow CX.
Data passed through QueryParameters is received by a webhook in Dialogflow CX. You can write code in the Dialogflow CX console to handle the passed data.
Do not nest an object within the customPayload object. Nested objects are sent as literal strings.
To pass custom data from your Dialogflow CX virtual agent back to the script, use the Custom Payload field in the Dialogflow CX console. Make sure you're in the console for the virtual agent you're using with CXone. Map this to your script using the customPayloadVarName (out) variable in the voice or chat Studio action in your script. For example, you can use this to set the next prompt's behaviors.
Parameters set using customPayload can only be used in the external webhook. If you want to set parameters for use outside the external webhook, set them in a Snippet action with the session_params field. For example:
```
{
	"session_params":
	{ 
		"name": "Winnie Le Pooh"
		"job": "Food critic"
		"location": "Hundred Acre Wood"
	}
}
```
Access the session parameters in the Dialogflow CX agent intent using the following syntax:

$session.params.name = Winnie Le Pooh

$session.params.job = Food critic

$session.params.location = 100 Acre Wood

Session parameters are only used with Dialogflow CX virtual agents. To achieve a similar result with Dialogflow ES, use contexts.
Speech context hints can be passed with custom payload in the speechContexts parameter. The value of speechContexts.phrases must be a Google class token for the hint you want to give. The token must match the language and locale of your contacts. For example:
```
DYNAMIC customPayload
customPayload.speechContexts.phrases="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"
customPayload.speechContexts.boost=10		
```

Best Practices for Custom Payload with Google Dialogflow ES

When using this action with Google Dialogflow ES, follow these best practices for integrating custom payloads:

CustomPayload is used to pass context for an intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. Context helps the virtual agent understand the user's intent. Contexts aren't required, but they help the virtual agent match an utterance What a contact says or types. to an intent.
In a Snippet action in your script, create a customPayload object that follows the format outlined in the Google Dialogflow ES documentation for REST Resource: projects.agent.sessions.context. The Studio online help provides additional information about dynamic data objects.
You can also pass custom data with customPayload without contexts. To do this, include standard JSON key-value pairs in a dynamic data object.
Speech contexts are passed in custom payload in the speech_contact parameter. You can see the contents of this parameter in Studio traces and application logs.
The customPayload dynamic object is passed as a virtual agent parameter as JSON, as shown in the example script.
Speech context hints can be passed with custom payload in the speechContexts parameter. The value of speechContexts.phrases must be a Google class token for the hint you want to give. The token must match the language and locale of your contacts. For example:
```
DYNAMIC customPayload
customPayload.speechContexts.phrases="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"
customPayload.speechContexts.boost=10		
```

Script Example

This example is not a complete script. Additional scripting work is required to use this action.

A script example showing the Voicebot Conversation action.

Download this script.

Script Example CustomPayload with Google Dialogflow ES

This example is not a complete script. Additional scripting work is required to use this action.

This script is an example of how to integrate custom payloads with Google Dialogflow ES virtual agents. This script uses the Voicebot Exchange action, but it will also work if you use TEXTBOT EXCHaNGE instead.

An example script showing how to handle custom payload with Google Dialogflow CX.

Download this script.

Example Script for Alternate Timeout Events

You can use different timeout events at different points in your script. For example, you might want to use different timeout events the first and second times the UserInputTimeout property is triggered. This example script shows one possible way to make this happen.

In this script, Snippet actions are used to create and increment a timeout counter. After the second timeout, a Snippet action is used to set a different timeout event. The alternate timeout event is passed from the Snippet action to the voicebot action through the automatedIntent property.

Download this script.